Integrating a Modern JavaScript Pipeline into a Django Application

Last updated: October, 2022

This is Part 3 of Modern JavaScript for Django Developers.

Welcome to Part 3!

In case you missed it—in Part 1 we covered how to organize a JavaScript codebase inside a Django project, and in Part 2 we provided a crash course in JavaScript tooling.

And now we finally start getting to the payoff: the nuts and bolts of integrating a modern JavaScript pipeline into our Django project.

In this part we'll finally stop with the theory, roll up our sleeves, and start getting building! By the end of this guide we'll have a React app and a Vue app running happily together in the same Django project.

In case not obvious—we don't actually recommend using React and Vue together in the same project. We just use this example because it helps demonstrate how the underlying pieces fit together and how they can be used to do whatever you want on the front end. Even using a framework at all is completely optional!

Sound fun? Let's get into it!

Let's start with the big picture setup.

Basically, we're going to create the JavaScript pipeline we covered in Part 2 as a standalone, separate environment inside our Django project.

Then to integrate with Django, the outputs (remember those bundle files?) will be static files that we'll drop into our templates wherever we need them. This will allow us to create anything from single-page apps, to reusable JavaScript libraries while maintaining the best of Django and JavaScript tooling.

Hopefully this makes sense, but if it doesn't, we'll get there through some concrete examples.

Ok, first the basics: where to put stuff.

At a high level, we suggest making your JavaScript project a subfolder in the root of your larger Django project. This guide uses a folder called ./assets/ for the front-end source files, though you could also use ./front-end/, ./js/ or whatever you want really.

The JavaScript project is where you'll do your front-end development—but remember Django will only work with the outputs generated by the bundler. So in addition to our ./assets/ directory, we'll also dump the outputs somewhere that Django's static files system can find them. A good default for this is an appropriately named root-level ./static/ folder.

Here's how that structure might look for a basic project modeled off the Django tutorial.

Congrats! You now have a JavaScript pipeline!

Now all that's left to do is to drop our bundle file in any Django template as a normal static file. This is all standard Django 101, but for completeness, let's show how that's done.

The basic template (let's call it hello_webpack.html) will look something like this:

You can serve the the template by adding this to a urls.py file.

This assumes hello_webpack.html is available from your template loader. You may also need to make sure you're properly serving files out of the static directory by adding the following to settings.py:

Once you've gotten everything properly set up, head to http://localhost:8000/hello-webpack/ and you should see the very exciting "hello webpack" message from index.js.

Hooray! You now have a front-end pipeline embedded in your Django app!

Ok, thus far we haven't actually done anything useful. So let's start exploring some of the benefits of having this front-end pipeline set up.

The first thing we might want to do is use a library. Let's continue along with the webpack guide and use the lodash utility library in our index.js file.

To do this we'll first install it via npm:

When installing a package that will be bundled into your production bundle, you should use npm install --save. If you're installing a package for development purposes (e.g. a linter, testing libraries, or—in the case earlier above with webpack—a bundler) then you should use npm install --save-dev.

Now we can update our index.js file to use lodash to generate our element:

Run npm run dev again to regenerate the bundle file and reload the page. If you did it right you should now see "Hello lodash" instead of "Hello webpack".

And we can now work with external JavaScript libraries! You can repeat this process for any other library you want to use.

Ok, so far so good. But we're still not doing anything really advanced—we're still basically using vanilla JavaScript and have just moved a few things around.

So now let's get fancy. Let's finally get that React app integrated into our project.

As we so lovingly alluded to in the introduction of this guide—React uses a language called JSX for its templating.

JSX is a language designed to let you easily use HTML in JavaScript code. It's mostly like HTML but slightly different and more opinionated in ways that can be confusing and frustrating when you first get started (for example, changing class to className everywhere). Oh and it also lets you inject JavaScript into it.

Anyway, the details of JSX aren't so important.

The important part is that browsers don't know how to speak JSX. So in order to use JSX in development you have to compile it into something that browsers understand. This is where Babel—our JavaScript compiler—finally enters the picture.

Babel can do all sorts of stuff (one of the best reasons to use it), but one of those things is parse JSX files.

It does this through a plugin ecosystem, and more specifically, through pre-configured setups—called presets—that work well for certain types of apps. Here we'll use the env-preset and react-preset, though presets also exist for TypeScript and other JavaScript flavors.

Anyway, those details aren't super important and it's not as complicated as it sounds!

The first thing we do is install Babel (@babel/core), its webpack loader babel-loader and our two presets, all as development dependencies:

While the main thing we wanted was preset-react, we're also bringing in preset-env, which allows you to use the latest JavaScript features without needing to worry about browser support. We recommend always using preset-env whenever you're using Babel—as it simplifies your life and prevents having to worry about the browser compatibility of various features.

Next we have to tell webpack to use this preset to process our files. This is done via a loader. We just need to add the following section to our webpack.config.js.

In English the summary is: "use Babel's env and react presets to compile all .js and .jsx files that aren't inside the node_modules directory".

Ok, now we're ready to try our React hello world application.

First add the line to your Django template in the (and before including the bundle file) like so:

Next we need to install React and ReactDOM:

Now we can update our index.js file to be a React version of hello world:

Run npm run dev again and refresh your page. You should now hopefully see "Hello, react!".

Congratulations, you now have a hybrid Django-React application!

Ok, so you probably don't actually want to use both React and Vue in the same Django application, but let's say that for some reason you decide to.

Both projects are incredibly opinionated about the whole build pipeline thing, and so figuring out how to use them together can be a nightmare. But now that we've wrapped our heads around our modern JavaScript primitives this is actually an easy task!

Vue has it's own recommended file format—one that includes templates that look even more like html than JSX but still aren't quite the same, as well as some JavaScript and styles.

Here's Vue's Hello.vue example:

{{ greeting }} Vue!

Anyway, without getting into too much detail, the main point is that just like JSX, browsers have no idea what to do with this format. So like React, we have to pass it through a compiler.

Thankfully, this is as simple as installing Vue and a new compiler (in this case vue-loader) and adding a new entry to our webpack.config.js.

Now we can add an index.vue file like the above, recompile our front end and voila! Hello Vue!

Try to set this up yourself following the React example and see if you can do it!

We're done with tooling! However, this isn't the end of the guide.

What comes next is the fun part: we can finally get coding!

In Part 4 we're going to use practical examples to start building out real applications in our new architecture. We'll cover things like interacting with APIs, passing information between the back end and front end, creating reusable libraries, and more.

Read on in Part 4: How to build a React application in a Django project.